/**
 * Copyright 2006 gworks.com.au
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. (http://www.apache.org/licenses/LICENSE-2.0)
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed 
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for 
 * the specific language governing permissions and limitations under the License.
 *
 * <dhamma-message src="Atisha (11th century Tibetan Buddhist master)">
 * 	The greatest achievement is selflessness. The greatest worth is self-mastery.
 * 	The greatest quality is seeking to serve others. The greatest precept is continual awareness.
 * 	The greatest medicine is the emptiness of everything. The greatest action is not conforming with the worlds ways.
 * 	The greatest magic is transmuting the passions. The greatest generosity is non-attachment.
 * 	The greatest goodness is a peaceful mind. The greatest patience is humility.
 * 	The greatest effort is not concerned with results. The greatest meditation is a mind that lets go.
 * 	The greatest wisdom is seeing through appearances. 
 * </dhamma-message>
 */
package org.javaongems.runtime.lang;

import java.io.UnsupportedEncodingException;
import java.net.URLDecoder;
import java.net.URLEncoder;

/**
 * <p>Provides basic string features that are not part of the JDK or commons lang 
 *    and attempt to simplify client code.</p>
 * <p>Responsibilities:
 * <ul>
 * 	<li> escape regular expression
 * 	<li> built in utf8 encoder/decoder without being forced to handle 
 * 		checked exception
 * </ul>
 * </p> 
 * <p>Collaborators:
 * <ul>
 * 	<li> {@link URLEncoder}
 * 	<li> {@link URLDecoder}
 * </ul>
 * </p>
 * 
 * @author Ashin Wimalajeewa (ash)
 */
final public class StringUtils extends org.apache.commons.lang.StringUtils {
	final static public String UTF8_ENC = "UTF-8";
	final static public String ESCAPE = "\\";
	final static public String NEW_LINE;
	final static public int NEW_LINE_SZ;
	
	private StringUtils() {
		// nothing to do
	}
		
	/**
	 * Command that escapes all regex special characters to nullify the regular 
	 * expression matching functionality
	 * @param strToEscape - the string to escape
	 * @return a string with all regular expression characters escaped 
	 */
	static public String escapeRegExChars(String strToEscape) {
		StringBuffer ret = new StringBuffer();
		int len = strToEscape.length();
		for (int i = 0; i < len; i++) {
			char ch = strToEscape.charAt(i);
			boolean escapeIt = false;
			switch (ch) {
			case '.':	case '\\':	case '?':	case '*':	case '+':
			case '&':	case ':':	case '{':	case '}':	case '[':
			case ']':	case '(':	case ')':	case '^':	case '$':
				escapeIt = true;
				break;
			}
			if (escapeIt)
				ret.append(ESCAPE);
			ret.append(ch);
		}
		return ret.toString();
	}
	
	/**
	 * Command that encodes the Url using utf8 encoding
	 * @param str - the string to encode
	 * @return the encoded string
	 * @see URLEncoder#encode(String, String)
	 */
	static public String encodeUrl(String str) {
		try {
			return URLEncoder.encode(str, UTF8_ENC);			
		} catch (UnsupportedEncodingException err) {
			throw new IllegalStateException(err.getMessage());
		}
	}
	
	/**
	 * Command that decodes the Url using utf8 encoding
	 * @param str - the string to decode
	 * @return the decoded string
	 * @see URLDecoder#decode(String, String)
	 */
	static public String decodeUrl(String str) {
		try {
			return URLDecoder.decode(str, UTF8_ENC);			
		} catch (UnsupportedEncodingException err) {
			throw new IllegalStateException(err.getMessage());
		}
	}
	
	static {
	    NEW_LINE = System.getProperty("line.separator");
	    NEW_LINE_SZ = NEW_LINE.length();
	}
}
